home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / db / db.man < prev    next >
Text File  |  1989-01-26  |  6KB  |  144 lines
  1. '\" $Header: /sprite/src/lib/c/db/RCS/db.man,v 1.2 89/01/26 16:49:40 douglis Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Db lib
  4. .BS
  5. .SH NAME
  6. Db \- manipulate simple database files
  7. .SH SYNOPSIS
  8. .nf
  9. \fB#include    <db.h>\fR
  10.  
  11. int
  12. \fBDb_WriteEntry\fR(\fIfile, buffer, index, size, lockHow\fP)
  13.  
  14. int
  15. \fBDb_ReadEntry\fR(\fIfile, buffer, index, size, lockHow\fP)
  16.  
  17. int
  18. \fBDb_Open\fR(\fIfile, size, handlePtr, writing, lockWhen, lockHow, numBuf\fP)
  19.  
  20. int
  21. \fBDb_Put\fR(\fIhandlePtr, buffer, index\fP)
  22.  
  23. int
  24. \fBDb_Get\fR(\fIhandlePtr, buffer, index\fP)
  25.  
  26. int
  27. \fBDb_Close\fR(\fIhandlePtr\fP)
  28.  
  29. .SH ARGUMENTS
  30. .AS Db_LockWhen *handlePtr
  31. .AP char *file in
  32. The name of a database file on which to perform operations.
  33. .AP char *buffer "in/out"
  34. A pointer to the area from which or to which to transfer the record.
  35. .AP int index out
  36. Which record to access in a database operation.
  37. .AP int size in
  38. The size of a record.
  39. .AP Db_LockHow lockHow in
  40. Method to use when locking the database.
  41. .AP Db_Handle *handlePtr "in/out"
  42. A pointer to a ``database handle''.  
  43. .AP int writing in
  44. If non-zero, the database file is opened in write-only mode, otherwise in
  45. read-only mode.
  46. .AP Db_LockWhen lockWhen in
  47. Determines when to lock the database for long-term accesses.
  48. .AP int numBuf in
  49. Number of records to buffer when reading from database.
  50. .BE
  51. .SH DESCRIPTION
  52. These functions provide shared access to files containing
  53. arbitrary numbers of fixed-length records.  There are two ways to
  54. access the files.  The simplest way to access a database file is to
  55. use \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR to open the file,
  56. access a record, and close the file again.  An alternative method is
  57. to use \fBDb_Open()\fR to obtain a \fBhandle\fP for the file, use
  58. \fBDb_Put()\fR or
  59. \fBDb_Get()\fR to write or read entries, respectively, and use Db_Close() to
  60. close the file when it is no longer needed.  In this case, the
  61. \fInumBuf\fR
  62. argument is used to specify how many records to buffer internally when doing
  63. reads (it must be specified as 0 for writes).
  64. .PP
  65. The Db library provides a simple locking facility to allow shared
  66. access to files, built on top of the \fBflock()\fR system call.  Database
  67. files can be accessed without using locks, or using the standard
  68. \fBflock()\fR call in blocking or non-blocking mode.  Unfortunately, hosts
  69. can hold locks when they crash, so a program that performs a blocking
  70. lock could wait indefinitely 
  71. for a lock if no additional mechanism is used.  The Db library allows
  72. locks to time out, and it can optionally break a lock if the lock
  73. times out.  The time-out period is currently fixed.  The different
  74. options are specified by the Db_LockHow type:
  75. .DS
  76. .ta 1c 2c 3c 4c 5c 6c 7c 8c
  77. typedef enum {
  78.     \fBDB_LOCK_NO_BLOCK\fP,        /* return immediately with error */
  79.     \fBDB_LOCK_POLL\fP,            /* poll the lock; time out if necessary */
  80.     \fBDB_LOCK_WAIT\fP,            /* wait indefinitely */
  81.     \fBDB_LOCK_BREAK\fP,        /* poll, plus break the lock if needed */
  82.     \fBDB_LOCK_NONE\fP,            /* do not lock the file at all */
  83. } Db_LockHow;
  84. .DE
  85. .PP
  86. The \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR procedures take a Db_LockHow
  87. parameter to determine how to lock the database file the one time it
  88. is accessed.  In addition to  a Db_Lock parameter, \fBDb_Open()\fR takes a
  89. Db_LockWhen argument to specify when to perform the lock.  Generally,
  90. when a file is going to be read or written sequentially, one would
  91. like to lock 
  92. it before starting to do I/O and unlock it after finishing.  If a file
  93. is going to be accessed repeatedly over a long period of time,
  94. however, it should be opened once but locked only during each access.
  95. These options are \fBDB_LOCK_OPEN\fP and \fBDB_LOCK_ACCESS\fP, respectively.  If
  96. the file is never to be locked, then the Db_LockWhen argument may be
  97. specified as \fBDB_LOCK_NEVER\fP or the Db_LockHow argument may be specified
  98. as \fBDB_LOCK_NONE\fP.
  99. .PP
  100. \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR provide access to a single record.
  101. They take the \fIfilename\fP to access; an \fIindex\fP into the file,
  102. the \fIsize\fP of a record; a pointer to a data \fIbuffer\fP;
  103. and the method of locking the database, \fIlockHow\fP.  All records
  104. must have the same size.  The index is zero-based, so \fIindex\fP 0
  105. refers to the first record in the file.
  106. .PP
  107. \fBDb_Open()\fR takes the same \fIfile\fP, \fIsize\fP, and \fIlockHow\fP
  108. arguments as \fBDb_WriteEntry()\fR and \fBDb_ReadEntry()\fR.  It also takes an
  109. argument, \fIwriting\fP, which indicates whether access will be
  110. writing (1) or reading (0); and another argument, \fInumBuf\fR, which
  111. specifies how many records to read from the file at once when doing
  112. reads.  The \fIlockWhen\fP argument is described 
  113. above; it indicates whether locking should be done for each access or at
  114. the time the file is opened.  \fBDb_Open()\fR returns a database handle in
  115. \fI*handlePtr\fP.  The storage for the handle must be allocated by the
  116. caller of \fBDb_Open()\fR.  A pointer to the handle must be used in later
  117. calls to \fBDb_Put()\fR, \fBDb_Get()\fR, or \fBDb_Close()\fR.
  118. .PP
  119. \fBDb_Put()\fR and \fBDb_Get()\fR are analogous to \fBDb_WriteEntry()\fR and
  120. \fBDb_ReadEntry()\fR.  They are used in cases when the database file is
  121. opened by \fBDb_Open()\fR, for use over an extended period of time.  The
  122. \fIhandlePtr\fP  argument must be a handle returned by \fBDb_Open()\fR. The
  123. \fIbuffer\fP  must be a pointer to an area of the size specified in the call
  124. to \fBDb_Open()\fR.  The \fIindex\fP  is an integer: if non-negative, it
  125. specifies a record number, like in calls to \fBDb_WriteEntry()\fR and
  126. \fBDb_ReadEntry()\fR.  If \fIindex\fP  is -1, it specifies that the access
  127. should be sequential: the
  128. record to be operated upon should be the one immediately following the
  129. last record read or written.  If \fBDb_Put()\fR
  130. or \fBDb_Get()\fR is called for the first time with an \fIindex\fP  of -1,
  131. the first record is written or read.
  132. .PP
  133. \fBDb_Close()\fR closes a file that was opened with \fBDb_Open()\fR.
  134. \fIHandlePtr\fP must point to a handle that was initialized by
  135. \fBDb_Open()\fR.
  136. .SH DIAGNOSTICS
  137. All routines return 0 if they complete successfully.  Upon error, they
  138. return -1 and the \fIerrno\fP variable  contains additional information
  139. about what error occurred.
  140. .SH KEYWORDS
  141. database, data base, lock, record, handle
  142. .SH SEE ALSO
  143. mig, ulog, flock, dbm
  144.